
<html><HEAD>
<LINK REL=STYLESHEET HREF="default.css" TYPE="text/css">
<TITLE>
Instantiating and configuring the server component</TITLE>
</HEAD>
<BODY>

<!-- Header -->
<p class="ancestor" align="right"><A HREF="dwprgugp49.htm">Previous</A>&nbsp;&nbsp;<A HREF="dwprgugp51.htm" >Next</A>
<!-- End Header -->
<A NAME="BABCBGAH"></A><h1>Instantiating and configuring the server component</h1>
<A NAME="TI2007"></A><p>You can write code to create an instance of the Web DataWindow
server component, and you can call its methods to create a Web DataWindow application.</p>
<A NAME="TI2008"></A><p>For information on the types of Web DataWindow server components,
see <A HREF="dwprgugp41.htm#BABCAFDD">"The Web DataWindow server
component and client control"</A>. </p>
<A NAME="TI2009"></A><h4>Two sets of methods</h4>
<A NAME="TI2010"></A><p>Two
sets of methods are available on the generic Web DataWindow server component:<A NAME="TI2011"></A>
<ul>
<li class=fi>Methods that are available for other DataWindow
controls</li>
<li class=ds>Methods used to configure the component and generate
HTML 
</li>
</ul>
</p>
<A NAME="TI2012"></A><h4>DataWindow control methods</h4>
<A NAME="TI2013"></A><p>DataWindow control methods supported by the generic server
component include sorting, filtering, validation, and get and set
methods. When you call one of these methods on the server component,
the server reloads the page in the browser.</p>
<A NAME="TI2014"></A><p>Methods with more than one syntax have a different form for
each syntax to overcome restrictions on the use of overloading.
For example, the ClearValues method takes a string as an argument
and the ClearValuesByColNum method takes a number. </p>
<A NAME="TI2015"></A><p>For a complete list of supported DataWindow control methods,
see the <i>DataWindow Reference</i>
 or the online
Help. </p>
<p><img src="images/note.gif" width=17 height=17 border=0 align="bottom" alt="Note"> <span class=shaded>Examining server component methods</span> <A NAME="TI2016"></A>You can view the generic <ABBR title = "e a server" >EAServer</ABBR> component
methods on the Components page of the System Tree or in <ABBR title = "e a server" >EAServer</ABBR> Manager.</p>
<A NAME="TI2017"></A><h4>Configuration and generation methods</h4>
<A NAME="TI2018"></A><p>Other methods are available to set up the component, retrieve
data, establish persistent values needed by your Web page, and generate
HTML. </p>
<A NAME="TI2019"></A><p>If you use a custom server component, there are additional
configuration tasks. For more information, see <A HREF="dwprgugp51.htm#BEIEHDDG">"Using a custom server component"</A>. </p>
<p><img src="images/note.gif" width=17 height=17 border=0 align="bottom" alt="Note"> <span class=shaded>Mixed case method names</span> <A NAME="TI2020"></A>The methods of the generic <ABBR title = "e a server" >EAServer</ABBR> server
component use mixed case names and all the examples in this section
use mixed case. If you write your own server component, the methods
of the component you generate are all lowercase. (You can use the
sample <i>PBDWRMT.PBL</i> as a starting point if you want
the methods described here.) </p>
<A NAME="TI2021"></A><h4>Coding steps</h4>
<A NAME="TI2022"></A><p>In your server-side script, you will code these tasks:<A NAME="TI2023"></A>
<ol>
</li>
<li class=ds>Instantiate the component.</li>
<li class=ds>Load the DataWindow object.</li>
<li class=ds>Control what HTML is generated (for example, by
specifying what functionality to include and what browser to target).</li>
<li class=ds>Specify the database connection and retrieve data.</li>
<li class=ds>Pass page-specific data to the reloaded page.</li>
<li class=ds>Pass user action information to the server component.</li>
<li class=ds>Insert the generated HTML in the page template.
</li>
</ol>
</p>
<A NAME="TI2024"></A><p>Sample code for some of these tasks follows. For detailed
information about the methods used in the examples, see the <i>DataWindow
Reference</i>
 or the online Help.</p>
<A NAME="BEIIGDFI"></A><h2>Instantiating the component</h2>
<A NAME="TI2025"></A><p>You can instantiate a Web DataWindow component in the following
manner:<p><PRE> &lt;%@ page contentType="text/html; charset=UTF-8" %&gt;</PRE><PRE> &lt;%@ page import="org.omg.CORBA.ORB" %&gt;</PRE><PRE> &lt;%@ page import="org.omg.CosNaming.NamingContext" %&gt;</PRE><PRE> &lt;%@ page import=          "org.omg.CosNaming.NamingContextHelper" %&gt;</PRE><PRE> &lt;%@ page import="org.omg.CosNaming.NameComponent" %&gt;&lt;%@ page import="DataWindow.*" %&gt;</PRE><PRE> </PRE><PRE> String dwGenerator = "DataWindow/HTMLGenerator115";</PRE><PRE> HTMLGenerator115 dwGen = null;</PRE><PRE> </PRE><PRE> java.util.Properties props =new java.util.Properties();</PRE><PRE> props.put("org.omg.CORBA.ORBClass",<br>   "com.sybase.CORBA.ORB");</PRE><PRE> props.put("com.sybase.CORBA.NameServiceURL",    "iiop://testmachine:2000");</PRE><PRE> ORB orb = ORB.init((String[])null, props);</PRE><PRE> try {</PRE><PRE>       NamingContext cntx = NamingContextHelper.narrow       (orb.resolve_initial_references("NameService"));</PRE><PRE>          NameComponent[] name = {new        NameComponent(dwGenerator,"")};</PRE><PRE>          SessionManager.Factory factory =        SessionManager.FactoryHelper.narrow<br>         (cntx.resolve(name));</PRE><PRE>       dwGen =         HTMLGenerator115Helper.narrow(factory.create<br>          ("jagadmin",""));</PRE><PRE> } catch(org.omg.CORBA.ORBPackage.InvalidName ie) {</PRE><PRE>         out.print("Error: " + ie.getMessage()); </PRE><PRE> } catch (org.omg.CosNaming.NamingContextPackage.NotFound ne) {</PRE><PRE>         out.print("Error: " + ne.getMessage()); </PRE><PRE> } catch </PRE><PRE> (org.omg.CosNaming.NamingContextPackage.CannotProceed     ce) {</PRE><PRE>         out.print("Error: " + ce.getMessage()); </PRE><PRE> } catch </PRE><PRE> (org.omg.CosNaming.NamingContextPackage.InvalidName     ie1) {</PRE><PRE>         out.print("Error: " + ie1.getMessage()); }</PRE></p>
<A NAME="BABJJDCG"></A><h2>Loading the DataWindow object</h2>
<p><b>SetDWObject</b>   The next step is to specify
the PBD or PBL file that contains the DataWindow object and the
name of the DataWindow object. You do not need to specify the location
of the file, but it must be available on the component server in
a directory on the server's path (or on the system path
if the <ABBR title = "e a server" >EAServer</ABBR> component is running
as a service or if you are using COM+): <p><PRE>  retVal = dwGen.SetDWObject ("htgenex.pbl",</PRE><PRE>         "d_tabular_dept");</PRE></p>
<A NAME="TI2026"></A><p>You can also specify a:<A NAME="TI2027"></A>
<ul>
<li class=fi>Source definition
(SRD) file containing the source for a DataWindow object. You can
export a DataWindow definition to an SRD file in the Library painter or
System Tree.</li>
<li class=ds>Powersoft report (PSR) file containing a DataWindow
object plus data. You can save a PSR file from the DataWindow painter.</li>
<li class=ds>DataWindow Container component on <ABBR title = "e a server" >EAServer</ABBR> containing multiple DataWindow
object definitions
</li>
</ul>
.</p>
<A NAME="TI2028"></A><p>For SRD and PSR files, specify an empty string for the DataWindow
name:<p><PRE> dwServer.SetDWObject("myreport.psr", "" );</PRE></p>
<A NAME="TI2029"></A><p>For DataWindow Container components, use the the SetDWObjectEx
method:<p><PRE> dwServer.SetDWObjectEx ("d_emp");</PRE></p>
<A NAME="BABCBBAI"></A><h2>Controlling what is generated </h2>
<A NAME="TI2030"></A><h4>Disabling features of the client control</h4>
<p><b>SetWeight</b>   Although the server component generates a considerable amount of
HTML or XHTML and JavaScript for the Web DataWindow client control, it
is still no more than an average image file. However, to reduce
the size of the control on the client, you can instruct the component
to leave out code for features you are not using. You can tell the
component to omit code for:<A NAME="TI2031"></A>
<ul>
<li class=fi>Updating data</li>
<li class=ds>Validating newly entered data</li>
<li class=ds>Client-side events</li>
<li class=ds>Allowing client-side scripts to call methods of
the client control</li>
<li class=ds>Applying display formats to newly entered data
</li>
</ul>
</p>
<A NAME="TI2032"></A><p>You can disable any of these on the Web Generation property
page in the DataWindow painter or with the SetWeight method. False
for a particular argument means no code for that feature is generated. </p>
<A NAME="TI2033"></A><p>This statement enables all features:<p><PRE> dwGen.SetWeight(true, true, true, true, true);</PRE></p>
<A NAME="TI2034"></A><p>If updating of data is false, no validation or display formatting
code is generated either. In this statement, it does not matter
what the second and fifth arguments are, because the first argument
for updating data is false:<p><PRE> dwGen.SetWeight(false, false, true, true, false);</PRE></p>
<A NAME="TI2035"></A><p>This statement turns off the client-side scripting capability:<p><PRE> dwGen.SetWeight(true, true, true, false, true);</PRE></p>
<A NAME="TI2036"></A><p>Updating data and display formatting add the most code to
the client-side control. Date processing also generates additional
code. For the smallest client control, turn on only the features
you need and make sure your DataWindow object does not have any
date columns.</p>
<A NAME="TI2037"></A><h4>Naming the client control</h4>
<p><b>SetHTMLObjectName</b>   You need to provide a name for the Web DataWindow client control.
The name is used for page parameters and client-side events. If there
is more than one Web DataWindow client control on the Web page,
each needs a unique name.</p>
<A NAME="TI2038"></A><p>This code uses the same name for the server component variable
and the client control:<p><PRE>     dwGen.SetHTMLObjectName ("dw_1");</PRE></p>
<p><img src="images/note.gif" width=17 height=17 border=0 align="bottom" alt="Note"> <span class=shaded>XML Web DataWindow</span> <A NAME="TI2039"></A>If you are using an XML Web DataWindow with a custom XHTML
template, the object name in the template must match the name of
the client control (dw_1 in the example).</p>
<A NAME="TI2040"></A><h4>Optimizing HTML for a browser</h4>
<p><b>SetBrowser </b>   The Web DataWindow can generate HTML optimized for particular
browsers and versions. In particular, it can generate code for Microsoft
and Netscape browsers. The browser might be different
each time the server component is instantiated by a different client,
so this information cannot be preset in the DataWindow painter.
You can tell it what browser and version to target in the server-side
script. In the painter, you can set the HTML Version property to
specify what level of HTML to generate if the browser is not recognized. </p>
<A NAME="TI2041"></A><p>For information on what HTML features the DataWindow uses
for different browsers, see the <i>DataWindow Reference</i>
 or
the HTMLGen.property topic in online Help.</p>
<A NAME="TI2042"></A><p>At runtime, the HTTP header sent from the client browser to
the Web server contains the User-Agent or HTTP_USER_AGENT
value, which the server component can use to identify the client
browser.</p>
<A NAME="BABCJGCI"></A><h2>Specifying the database connection and retrieving data</h2>
<A NAME="TI2043"></A><h4>Specifying connection information</h4>
<p><b>SetTrans</b>   You provide connection information for the server component
with the SetTrans method. The arguments you specify depend on the
type of connection. For an ODBC connection to SQL Anywhere, you
specify all the connection information in the dbParm argument.</p>
<A NAME="TI2044"></A><p>In <ABBR title = "e a server" >EAServer</ABBR>, you must also
set up a connection cache for the component, described in <A HREF="dwprgugp44.htm#BEIJCFJJ">"Creating a connection cache
on <ABBR title = "e a server" >EAServer</ABBR> 5.x"</A>.</p>
<A NAME="TI2045"></A><p>The data source must be defined on the server machine. It
must be a system DSN on <ABBR title = "e a server" >EAServer</ABBR> if
the component is running as a service. This statement connects to
the EAS Demo DB sample database:<p><PRE> dwGen.SetTrans("ODBC","ConnectString='DSN=EAS Demo DB V115;UID=dba;PWD=sql'",        "", "", "", "", "");</PRE></p>
<A NAME="TI2046"></A><p>If you are using the XML Web DataWindow, it is best to call
the SetPageSize method to limit the number of rows per page:<p><PRE> dwGen.SetPageSize(2);</PRE></p>
<p><img src="images/note.gif" width=17 height=17 border=0 align="bottom" alt="Note"> <span class=shaded>Using Adaptive Server Enterprise</span> <A NAME="TI2047"></A>PowerBuilder and <ABBR title = "e a server" >EAServer</ABBR> use
slightly different versions of the CT-Lib software to connect to
Adaptive Server Enterprise via Open Client. In the PowerBuilder
development environment, you use the SYC native database interface
to connect to the database, but you must use SYJ as the first argument to
SetTrans to connect to ASE in <ABBR title = "e a server" >EAServer</ABBR>. </p>
<A NAME="TI2048"></A><h4>Retrieving data</h4>
<p><b>Retrieve</b>   To tell the server component to retrieve data when the DataWindow object
does not have retrieval arguments, you call the Retrieve method:<p><PRE>     retVal = dwGen.Retrieve();</PRE></p>
<A NAME="TI2049"></A><h4>Specifying retrieval arguments</h4>
<p><b>RetrieveEx</b>   If the DataWindow
object expects retrieval arguments, call RetrieveEx:<p><PRE> dwGen.RetrieveEx("60000");</PRE></p>
<A NAME="TI2050"></A><p>Typically, the retrieval arguments are not constants. They
are page parameters passed to the page from another page where the
user filled in a form or clicked a hyperlink. If the DataWindow
expects more than one retrieval argument, the arguments must be
passed in a single string. The arguments in the string must be separated
by newline characters (\n), and individual values cannot
contain newline characters as part of the value. Array values must
be separated by tab characters (\t).</p>
<A NAME="TI2051"></A><p>Getting the retrieval argument from another page works the
first time the page is loaded. The retrieval arguments have to be
page parameters each time the page is reloaded. To specify page
parameters for the reloaded page, you use the SetSelfLink method,
described next.</p>
<A NAME="BABDECHH"></A><h2>Passing page-specific data to the reloaded page</h2>
<A NAME="TI2052"></A><h4>Using self link information</h4>
<A NAME="TI2053"></A><p>The first time the client browser requests the page template,
it can pass page-specific information using GET or POST, and the
page can use those values in the server-side scripts. However, when
the page is reloaded because of user interactions with the Web DataWindow,
that information is not passed to the page automatically. </p>
<A NAME="TI2054"></A><p>To make the information available, you specify a <i>selflinkargs</i> string
with values that become page parameters in the reloaded page. Typically,
you would use self-link parameters to keep available:<A NAME="TI2055"></A>
<ul>
<li class=fi>Login information from another page</li>
<li class=ds>The DataWindow object name</li>
<li class=ds>Retrieval arguments for the DataWindow object
</li>
</ul>
</p>
<A NAME="TI2056"></A><p>To provide these values when the page is reloaded, you use
the SetSelfLink method, which takes as arguments the URL of the
page template as well as the selflinkargs string.</p>
<A NAME="TI2057"></A><p>To reload the page correctly in response to user actions,
the server component needs to know the URL of the page template.
You can get this information from the name property of the document
object header or the SCRIPT_NAME server variable.</p>
<A NAME="TI2058"></A><h4>Building a self-link argument string</h4>
<A NAME="TI2059"></A><p>Self-link arguments become page parameters in the reloaded
page. Your script typically looks at an existing page parameter
and re-creates it using a self-link argument. The syntax for specifying
a self-link argument string is:<p><PRE><i>pageparam1</i>='<i>expr1</i>'|<i>pageparam2</i>='<i>expr2</i>'...|<i>pageparam</i><i>n</i>='<i>expr</i><i>n</i>'</PRE></p>
</p>
<A NAME="TI2060"></A><p>The string can contain one or more page parameter and expression
pairs separated by pipes ( | ). Each expression is a DataWindow
expression that evaluates to a string. Usually you specify constant
string values that are already values of page parameters rather
than expressions. </p>
<A NAME="TI2061"></A><p>The expression is enclosed in quotes, and if the value is
a constant, it must also be enclosed in quotes. For example, if
a page parameter has the value <i>Johnson</i>, the
value of the expression must be enclosed in two sets of quote marks: <FONT FACE="Courier New">'"Johnson"'</FONT></p>
<A NAME="TI2062"></A><p>To get the value from the current Logname parameter, which
is already defined for the page, you build the expression using
the Logname page parameter. The single quotes and inner double quotes
are embedded in the expression. The current value is inserted between
the quotes:<p><PRE> String logname = (String)    request.getParameter("Logname");</PRE><PRE> String linkargs = </PRE><PRE>         "logname='\"" + logname + "\"'";</PRE></p>
<A NAME="TI2063"></A><p>An expression does not need the inner quotes:<p><PRE> String linkargs = "date='String(Today())'";</PRE></p>
<A NAME="TI2064"></A><h4>Passing the URL and argument string to SetSelfLink</h4>
<p><b>SetSelfLink</b>   Use the URL and the link arguments string as arguments to
the SetSelfLink method:<p><PRE> dwGen.SetSelfLink(pageName, linkargs);</PRE></p>
<A NAME="TI2065"></A><h4>Retrieval arguments as self-link values</h4>
<A NAME="TI2066"></A><p>The first time the page is loaded, the retrieval argument
might be:<A NAME="TI2067"></A>
<ul>
<li class=fi>A page parameter passed from another
page. The user might have clicked a URL that included the value
or filled in a form that posted the value.</li>
<li class=ds>A new value calculated in the current script.
</li>
</ul>
</p>
<A NAME="TI2068"></A><p>If the value is a page parameter, then you can re-create the
page parameter using SetSelfLink. If the value is from some other
source, you need to write code that gets the value from the source
(which might be a page parameter) the first time the page is loaded
and from a page parameter when it is reloaded.</p>
<A NAME="TI2069"></A><h4>Examples</h4>
<A NAME="TI2070"></A><p>These examples show code that works with the types of values
listed above. They illustrate how to get each type of value and
use it in both RetrieveEx and SetSelfLink method calls. </p>
<p><b>Value from another page</b>   If the user entered a product ID in a form to get detailed
information on the product, the product ID is passed to the product report
template as a page parameter. The page parameter should always exist because
it comes from the calling page, but the code provides a default
value anyway:<p><PRE> String prod_id;</PRE><PRE> prod_id=(String) request.getParameter("ProdID"); </PRE><PRE> if (prod_id == null){</PRE><PRE>    prod_id = "1";</PRE><PRE> }</PRE><PRE> dwGen.RetrieveEx(prod_id);</PRE><PRE> dwGen.SetSelfLink(        "ProdID=" + "'\"" + prod_id + "\"'");</PRE></p>
<p><b>Multiple values</b>   In this example, a Web page with a form prompts the user for a
user name and a product category and the level of detail the user
wants to see. The code uses the product category as a retrieval
argument for the Web DataWindow. The script selects a DataWindow
object based on the level of detail. All three values are carried
over each time the page is reloaded:<p><PRE> // Get product category as a retrieval arg</PRE><PRE> String retrievearg, username, rptlevel, dw;</PRE><PRE> retrievearg =     (String)request.getParameter("category");</PRE><PRE> if (retrievearg == null) {</PRE><PRE> retrievearg = "all";</PRE><PRE> }</PRE><PRE> int rtn = dwGen.RetrieveEx(retrievearg);</PRE><PRE> if (rtn &lt; 0) {</PRE><PRE>     ... // Check for error</PRE><PRE> }</PRE><PRE> // Get the user name</PRE><PRE> username =(String)request.getParameter("username");</PRE><PRE> if (username     != null){</PRE><PRE> out.print("&lt;P&gt;Dear " + username + "&lt;/P&gt;");</PRE><PRE> }</PRE><PRE> out.print("&lt;P&gt;Here is the report you<br>    requested.&lt;/P&gt;");</PRE><PRE> </PRE><PRE> // Choose DW based on detail level requested</PRE><PRE> rptlevel=(String)request.getParameter("reportlevel");</PRE><PRE> if (rptlevel == "detail"){</PRE><PRE>     dw = "d_product_detail";</PRE><PRE> } else if (rptlevel == "summary"){</PRE><PRE>     dw = "d_product_summary";</PRE><PRE> } else {</PRE><PRE>     dw = (String) request.getParameter("dw");</PRE><PRE>     if (dw == null} {</PRE><PRE>     out.print ("&lt;P&gt;Error selecting report");</PRE><PRE>     //handle error or halt processing ...</PRE><PRE> }</PRE><PRE> dwGen.SetDWObject("productrpt.pbd", dw);</PRE><PRE> </PRE><PRE> // Tell the server component to recreate the </PRE><PRE> // page parameters generated for the browser</PRE><PRE> String linkargs = "username='\"" + username + "\"'"</PRE><PRE>  + "|category= '\"" + retrievearg + "\"'"</PRE><PRE>  + "|dw= '\"" + dw + "\"'";</PRE><PRE> </PRE><PRE> dwGen.SetSelfLink( pageName, linkargs );</PRE></p>
<A NAME="TI2071"></A><h2>Passing user actions to the server component</h2>
<p><b>SetAction</b>   When the user clicks a DataWindow button, action information
is passed back to the page server as context and action page parameters.
Your server-side script needs to access those page parameters and
call SetAction so the server component can apply the action to the
generated HTML. </p>
<A NAME="TI2072"></A><p>The names of the parameters use the object name specified
in the SetHTMLObjectName method, for example: dw_1_action
and dw_1_context. You can also specify the object
name on the Web Generation tab page in the DataWindow painter.</p>
<A NAME="TI2073"></A><p>You can include buttons for scrolling to other pages of data
and for retrieving and updating data and inserting and deleting
rows. When these button actions occur, the change is sent back to
the server component and the change is made in the DataWindow buffer.
If the user clicks an update button, the update method is called
in the component without any other scripting needed. </p>
<p><img src="images/note.gif" width=17 height=17 border=0 align="bottom" alt="Note"> <span class=shaded>No need to call methods</span> <A NAME="TI2074"></A>You can call server component methods directly for retrieving
data, updating, inserting and deleting rows, and so forth. However,
remember that button clicks invoke the actions. You do not need
to call the methods too.</p>
<A NAME="TI2075"></A><p>This code checks whether parameters have been defined (meaning
that the page is a reloaded page) and if so, calls SetAction to
send the action information to the server component:<p><PRE> int retVal;</PRE><PRE> String dw_1_action =(String)request.GetParameter     ("dw_1_action");</PRE><PRE> String dw_1_context = (String)request.GetParameter     ("dw_1_context");</PRE><PRE> if (dw_1_context == null){</PRE><PRE>     dw_1_context = " ";</PRE><PRE> }</PRE><PRE> // Check if we need to perform the action</PRE><PRE> if (dw_1_action!=null){</PRE><PRE>   retVal = dwGen.<i>SetAction</i>(dw_1_action, dw_1_context);</PRE><PRE>   if (retVal &lt; 0 ) {</PRE><PRE>     out.print("Error on SetAction: "            + retVal + "&lt;BR&gt;");</PRE><PRE>     out.print(dwGen.GetLastErrorString()+ "&lt;BR&gt;");</PRE><PRE>   }</PRE><PRE> }</PRE></p>
<A NAME="TI2076"></A><h2>Inserting the generated HTML or XHTML into the page</h2>
<p><b>Generate</b>   After the server script has done all the setup, it calls the
Generate function, which returns the generated HTML as a string. </p>
<A NAME="TI2077"></A><p>Use out.print to insert code in the page template:<p><PRE> out.print( dwGen.Generate() );</PRE></p>
<p><b>GenerateXHTML and GenerateXMLWeb</b>   You return the Web DataWindow in XHTML with the GenerateXHTML
command:<p><PRE> out.print( dwGen.GenerateXHTML() );</PRE></p>
<A NAME="TI2078"></A><p>The GenerateXMLWeb method generates the content, layout, style,
and client-side functionality of the DataWindow separately
in XML, XSLT, CSS, and JS files. It returns the browser-specific
XSLT transformation script that uses the generated files to render
the DataWindow in XHTML on the client side:<p><PRE> out.print( dwGen.GenerateXMLWeb() );</PRE></p>

